home *** CD-ROM | disk | FTP | other *** search
/ Deutsche Edition 1 / Deutsche Edition 1.iso / amok / 021-030 / amok22 / lists / lists.def next >
Text File  |  1993-11-04  |  7KB  |  187 lines
  1. (**********************************************************************
  2.  
  3.     :Program.    Lists.def
  4.     :Contents.   Generic data type: List
  5.     :Author.     Nicolas Benezan [bne]
  6.     :Address.    Postwiesenstr. 2, D7000 Stuttgart 60
  7.     :Phone.      711/333679
  8.     :Copyright.  Public Domain
  9.     :Language.   Modula-2
  10.     :Translator. M2Amiga AMSoft 3.11
  11.     :Imports.    TaskMemory [bne]
  12.     :History.    V1.0 [mif] 13.Sep.1988
  13.     :History.    V1.1 [bne] 8.Feb.1989 (V1.0 modified)
  14.     :History.    V2.0d [bne] 4.Mar.1989 (complete new version)
  15.     :History.    V2.1a [bne] 22.Mar.1989 (Bug in CreateList() fixed)
  16.  
  17. **********************************************************************)
  18.  
  19. DEFINITION MODULE Lists;
  20.  
  21. FROM SYSTEM     IMPORT BYTE, ADDRESS;
  22. FROM Exec       IMPORT MinNode;
  23.  
  24. TYPE    List;
  25.         EntryPtr=POINTER TO Entry;
  26.         (* EntryPtr and Entry should be considered as opaque.
  27.            Do not access them directly unless you want to expand
  28.            the features of Lists *)
  29.         Entry=RECORD
  30.           node:MinNode;
  31.           dataSize:CARDINAL;
  32.           dataPtr:ADDRESS;
  33.         END;
  34.  
  35. VAR     ListsAllocProc:PROCEDURE(VAR ADDRESS,LONGINT);
  36.         ListsDeallocProc:PROCEDURE(VAR ADDRESS);
  37. (* defaults are TaskMemory.Allocate and TaskMemory.Deallocate *)
  38.  
  39. PROCEDURE CreateList(VAR list:List):BOOLEAN;
  40. (*:Semantic.    Creates an initializes a new list for further use
  41.   :Note.        Never use a list before having CreateList()ed it !!!
  42. *)
  43.  
  44. PROCEDURE AppendEntry(list:List;
  45.                       DataSize:CARDINAL;
  46.                       DataAddr:ADDRESS);
  47. (*:Semantic.    Appends data of given address and size to list
  48.   :Note.        Data will be actually a part of list, so don't reuse it
  49. *)
  50.  
  51. PROCEDURE AppendEntryC(list:List;
  52.                    VAR Data:ARRAY OF BYTE);
  53. (*:Semantic.    Allocates a new entry, copies data and appends it
  54.   :Output.      Data remains unchanged (VAR for efficiency)
  55. *)
  56.  
  57. PROCEDURE RemoveEntry(list:List;
  58.                   VAR entry:EntryPtr);
  59. (*:Semantic.    Removes an entry from list, does not delete its data
  60.   :Input.       Entry: entry to be removed
  61.   :Output.      Entry: always NIL
  62.   :Note.        complement of InsertEntry() or AppendEntry()
  63. *)
  64.  
  65. PROCEDURE DeleteEntry(list:List;
  66.                       entry:EntryPtr);
  67. (*:Semantic.    Removes an entry and deallocates its data
  68.   :Input.       Entry: entry to be removed
  69.   :Note.        complement of InsertEntryC() or AppendEntryC()
  70. *)
  71.  
  72. PROCEDURE DeleteList(VAR list:List);
  73. (*:Semantic.    DeleteEntry()s all entries and discards the list
  74. *)
  75.  
  76. PROCEDURE InsertEntry(list:List;
  77.                       Position:EntryPtr;
  78.                       DataSize:CARDINAL;
  79.                       DataAddr:ADDRESS);
  80. (*:Semantic.    Inserts an entry BEFORE a given position
  81.   :Semantic.    Data is not copied.
  82. *)
  83.  
  84. PROCEDURE InsertEntryC(list:List;
  85.                        Position:EntryPtr;
  86.                    VAR Data:ARRAY OF BYTE);
  87. (*:Semantic.    allocates a new entry, copies Data into it
  88.   :Semantic.    and InsertEntry()s it
  89.   :Output.      Data remains unchanged (VAR for efficiency)
  90. *)
  91.  
  92. PROCEDURE ListOk(list:List):BOOLEAN;
  93. (*:Semantic.    returns wether previous actions on list have
  94.   :Semantic.    been succesful.
  95.   :Result.      FALSE, if there have been one or more errors since
  96.   :Result.      the last call to ListOk(), otherwise TRUE
  97.   :Note.        Error conditions are:
  98.   :Note.         - No free memory while appending
  99.   :Note.         - No free memory while inserting
  100.   :Note.         - Remove an undefined (EntryPtr=NIL) entry
  101.   :Note.         - Read an undefined (EntryPtr=NIL) entry
  102.   :Note.         - Replace an undefined (EntryPtr=NIL) entry
  103.   :Note.         - Try to locate a not existing entry
  104.   :Note.           (Position>=NumEntries)
  105.   :Note.         - FirstEntry() of an empty list
  106.   :Note.         - LastEntry() of an empty list
  107.   :Note.        WARNING: not every possible error can be fixed.
  108.   :Note.        Operations on lists which are not properly initialised,
  109.   :Note.        for example, may crash the system!
  110. *)
  111.  
  112. PROCEDURE EntriesInList(list:List):CARDINAL;
  113. (*:Semantic.    returns how many entries are currently in the list
  114.   :Note.        keep in mind that the result is meaningless for
  115.   :Note.        shared lists unless executed Forbid()den
  116. *)
  117.  
  118. PROCEDURE ReadEntry(list:List;
  119.                     entry:EntryPtr;
  120.                 VAR DataSize:CARDINAL;
  121.                 VAR DataAddr:ADDRESS);
  122. (*:Semantic.    returns the address and size of the data
  123. *)
  124.  
  125. PROCEDURE ReadEntryC(list:List;
  126.                      entry:EntryPtr;
  127.                  VAR Data:ARRAY OF BYTE);
  128. (*:Semantic.    provides a copy of the data
  129. *)
  130.  
  131. PROCEDURE ReplaceEntry(list:List;
  132.                        entry:EntryPtr;
  133.                        DataSize:CARDINAL;
  134.                        DataAddr:ADDRESS);
  135. (*:Semantic.    replaces the old data in the specified entry with the
  136.   :Semantic.    new one. Neither is any data moved or copied, nor is
  137.   :Semantic.    any allocation/deallocation done.
  138.   :Note.        If you don't have a pointer to the old data, it will be 
  139.   :Note.        garbage!
  140. *)
  141.  
  142. PROCEDURE ReplaceEntryC(list:List;
  143.                         entry:EntryPtr;
  144.                     VAR Data:ARRAY OF BYTE);
  145. (*:Semantic.    copies Data into the data field of an entry
  146.   :Semantic.    Data must have same or smaller size than that field
  147.   :Note.        (size of the entry will not change if Data is smaller)
  148. *)
  149.  
  150. PROCEDURE LocateEntryAbs(list:List;
  151.                          Position:CARDINAL):EntryPtr;
  152. (*:Semantic.    returns a pointer to the entry referenced by its
  153.   :Semantic.    number (starting with 0 from the beginning)
  154.   :Result.      Pointer to the referenced entry
  155.   :Result.      undefined, if Position>=NumEntries(list)
  156. *)
  157.  
  158. PROCEDURE LocateEntryRel(list:List;
  159.                      VAR entry:EntryPtr;
  160.                          Offset:INTEGER):BOOLEAN;
  161. (*:Semantic.    positions forward (psitive Offset) or backward (negative)
  162.   :Result.      FALSE, if positioned after the last or before the 
  163.   :Result.      first entry
  164. *)
  165.  
  166. PROCEDURE Successor(VAR entry:EntryPtr):BOOLEAN;
  167. (*:Input.       entry: entry of which you want to know the successor
  168.   :Result.      TRUE, if entry (Input) has a successor, FALSE, if not
  169.   :Output.      entry: succesor if result is TRUE, otherwise undefined
  170. *)
  171.  
  172. PROCEDURE Predecessor(VAR entry:EntryPtr):BOOLEAN;
  173. (*:Input.       entry: entry of which you want to know the predecessor
  174.   :Result.      TRUE, if entry (Input) has a predecessor, FALSE, if not
  175.   :Output.      entry: predecessor if result is TRUE, otherwise undefined
  176. *)
  177.  
  178. PROCEDURE FirstEntry(list:List):EntryPtr;
  179. (*:Result.      pointer to the first entry, undefined if list is empty
  180. *)
  181. PROCEDURE LastEntry(list:List):EntryPtr;
  182. (*:Result.      pointer to the last entry, undefined if list is empty
  183. *)
  184.  
  185. END Lists.
  186.  
  187.